home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / Name.3 < prev    next >
Text File  |  1994-09-20  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_Name(3)            Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_Name,  Tk_PathName,  Tk_NameToWindow  -  convert  between
  12.      names and window tokens
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Tk_Uid
  18.      Tk_Name(_t_k_w_i_n)
  19.  
  20.      char *
  21.      Tk_PathName(_t_k_w_i_n)
  22.  
  23.      Tk_Window
  24.      Tk_NameToWindow(_i_n_t_e_r_p, _p_a_t_h_N_a_m_e, _t_k_w_i_n)
  25.  
  26. ARGUMENTS
  27.      Tk_Window    _t_k_w_i_n       (in)      Token for window.
  28.  
  29.      Tcl_Interp   *_i_n_t_e_r_p     (out)     Interpreter  to  use  for
  30.                                         error reporting.
  31.  
  32.      char         *_p_a_t_h_N_a_m_e   (in)      Character string contain-
  33.                                         ing path name of window.
  34. _________________________________________________________________
  35.  
  36.  
  37. DESCRIPTION
  38.      Each window managed by Tk has two names, a short  name  that
  39.      identifies a window among children of the same parent, and a
  40.      path name that identifies the window uniquely among all  the
  41.      windows belonging to the same main window.  The path name is
  42.      used more often in Tk than the short name;   many  commands,
  43.      like bind, expect path names as arguments.
  44.  
  45.      The Tk_Name macro returns a window's short  name,  which  is
  46.      the  same as the _n_a_m_e argument passed to Tk_CreateMainWindow
  47.      or Tk_CreateTopLevelWindow or Tk_CreateChildWindow when  the
  48.      window  was  created.   The  value  is returned as a Tk_Uid,
  49.      which may be used just like a string pointer  but  also  has
  50.      the  properties  of a unique identfier (see the manual entry
  51.      for Tk_GetUid for details).
  52.  
  53.      The Tk_PathName macro returns a hierarchical name for _t_k_w_i_n.
  54.      Path  names  have  a structure similar to file names in Unix
  55.      but with dots between elements instead of slashes:  the main
  56.      window   for   an   application   (one  created  by  calling
  57.      Tk_CreateMainWindow or  by  calling  Tk_CreateTopLevelWindow
  58.      with  a  NULL _p_a_r_e_n_t argument) has the path name ``.'';  its
  59.      children have names like ``.a'' and ``.b'';  their  children
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_Name(3)            Tk Library Procedures
  71.  
  72.  
  73.  
  74.      have  names like ``.a.aa'' and ``.b.bb''; and so on.  A win-
  75.      dow is considered to be be a child  of  another  window  for
  76.      naming  purposes if the second window was named as the first
  77.      window's _p_a_r_e_n_t when the first window was created.  This  is
  78.      not always the same as the X window hierarchy.  For example,
  79.      a pop-up is created as a child of the root window,  but  its
  80.      logical  parent will usually be a window within the applica-
  81.      tion.
  82.  
  83.      The procedure Tk_NameToWindow returns the token for a window
  84.      given its path name (the _p_a_t_h_N_a_m_e argument) and another win-
  85.      dow belonging to the same main window (_t_k_w_i_n).  It  normally
  86.      returns  a token for the named window, but if no such window
  87.      exists Tk_NameToWindow leaves an error  message  in  _i_n_t_e_r_p-
  88.      >_r_e_s_u_l_t   and   returns   NULL.    The   _t_k_w_i_n  argument  to
  89.      Tk_NameToWindow is needed because path names are only unique
  90.      within  a  single application hierarchy.  If, for example, a
  91.      single process has opened two main windows, each will have a
  92.      separate  naming  hierarchy  and  the  same  path name might
  93.      appear in each of the hierarchies.  Normally  _t_k_w_i_n  is  the
  94.      main  window  of the desired hierarchy, but this need not be
  95.      the case:  any window in the desired hierarchy may be used.
  96.  
  97.  
  98. KEYWORDS
  99.      name, path name, token, window
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.